iT邦幫忙

2024 iThome 鐵人賽

DAY 16
0
IT 管理

數位產品PM的開發小抄本系列 第 16

[Day16]_數位產品PM的開發小抄本_The Documentation System關鍵元件參照說明Reference

  • 分享至 

  • xImage
  •  

在一個階段,是要說明建構這一個產品和服務的技術執行內容,會參照到的說明規則,比如API、函數、UI等相關主要建構服務的元件項目

撰寫Reference guides關鍵元件參照說明的注意事項:

  • 關鍵元件參照說明是機制及其操作方法的技術說明。
  • 關鍵元件參照說明只有一項工作:描述(to describe)。
  • 所描述的內容:關鍵類別、函數、API,因此它們應該列出函數、欄位、屬性和方法等內容,並列出如何使用它們。
  • 技術參考可以包含範例來說明用法,但不應試圖解釋基本概念或如何實現常見任務,僅作說明用法。
  • 使用機制的基本描述 , 例如,如何實例化特定類,或呼叫特定方法,或將某些內容傳遞給函數時必須採取的預防措施。
  • 作為技術參考的功能的一部分,並且強調不要與操作指南(How-to-guide)混淆 - 描述軟體的正確使用(技術參考)並不等同於展示如何使用它來實現某個目標(操作方法文件)。
  • 對一些開發人員來說,關鍵元件參照說明就能想到的唯一參考文件。他們已經了解他們的軟體,他們知道如何使用它。他們所能想像的只是其他人可能需要的只是有關它的技術資訊。
  • 說明相關元件資訊運作基本事實或原理
  • 有關潛在問題的警示說明(Error code)
  • 關鍵元件參照說明可提供與程式碼庫相同的結構,以便開發人員可以同時參照程式碼和文件。
  • 在關鍵元件參照說明中,結構、語氣、格式都必須一致——就像百科全書或字典一樣。
  • 關鍵元件參照說明盡可能清晰、完整地描述。任何其他內容(解釋、討論、指導、推測、意見)不僅會分散注意力,而且會使其更難以使用和維護。
  • 避免使用關鍵元件參照說明指導如何實現目標,超出使用產品或服務的基本範圍,並且不允許對概念進行解釋或對主題進行討論。
  • 請酌情連結到操作指南、解釋和引導教學。
  • 描述必須準確並保持最新。機器與您的描述之間的任何差異都將不可避免地導致用戶誤入歧途。
  • 描述(Description)就是本文的全部內容,以完整、準確的形式列出工具的功能、指令和選項。
  • 這不是一本友好或引人入勝的讀物,而目的是盡可能快速且不受干擾地查找有關產品功能的資訊。

Take away

關鍵元件參照說明,可以認知為是將關鍵元件和機制的使用說明,讓使用者可以了解關鍵元件的運作原理後,就可以直接進行操作,完成目標。

該階段先僅作為,關鍵元件的使用說明,並非完整描述其內容及機制細節,避免使用者閱讀的負擔,可以快速解決使用者需求,有利於展開行動。

關鍵元件參照說明,是作為一個查詢資訊使用,不做完友善讀物,因此以高效查詢閱讀為優先目標。


上一篇
[Day15]_數位產品PM的開發小抄本_The Documentation System操作指南How-to guides
下一篇
[Day17]_數位產品PM的開發小抄本_The Documentation System資訊解釋Explanation
系列文
數位產品PM的開發小抄本30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

1 則留言

0
Leodaddy
iT邦新手 3 級 ‧ 2024-09-30 09:09:44

reference這很重要!!畢竟專案內每個人的專業都不同,又不可能每次都來問PM,直接有reference guides超有用的!

我要留言

立即登入留言